Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

How to use ROSARIA

For an introductory overview of using ROS with Adept MobileRobots robots, see The AMR Pioneer Robots Portal. This page also includes links to other ROS nodes that you may need for accessory devices on your robot.

Reading the other introductory documentation on this wiki is highly recommended, if you have not already: ROS/Introduction, ROS/Concepts, ROS/Tutorials, ROS/CommandLineTools.

Certain parts of this tutorial have been edited for specific ROS versions.

Select your ROS version here:

melodic noetic   Show EOL distros: 

Note, on October 11, 2013, ROSARIA was renamed to rosaria and the source code repository was moved to github from Google code. The instructions for ROS hydro have been updated for this changes, but instructions for prior versions below have not yet been tested and updated for the new name and repository location.

Install ROS

If you have not yet installed ROS, see the ROS installation instructions. The easiest OS to install ROS on is Ubuntu. Install at least the "base" set of packages.

Create your ROS workspace

If you have not yet created your ROS overlay workspace in your home directory, do so now.

rosws init ~/ros-fuerte /opt/ros/fuerte

source ~/ros-fuerte/setup.bash

echo "source ~/ros-fuerte/setup.bash >> ~/.bashrc

. /opt/ros/groovy/setup.bash

. /opt/ros/hydro/setup.bash

. /opt/ros/indigo/setup.bash

. /opt/ros/jade/setup.bash

. /opt/ros/kinetic/setup.bash

. /opt/ros/lunar/setup.bash

. /opt/ros/melodic/setup.bash

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
catkin_init_workspace
cd ~/catkin_ws
catkin_make

You can setup separate workspaces for different versions of ROS if more than one is installed.

Source setup.bash

Every time you want to use the catkin workspace to build packages, you must source the special devel/setup.bash script:

cd catkin_ws
. devel/setup.bash

You must do this for every new shell or terminal window you open.

If you only use one catkin workspace, you can add this command to your .bashrc file, so that it automatically occurs for every new shell or terminal window you run.

For example, if your catkin workspace is catkin_ws in your home directory, edit .bashrc in your home directory and add the following line to the end of the file. The .bashrc file is normally hidden, but you can still reference it to edit it or enable "Show hidden files" in the file browser preferences.

. ~/catkin_ws/devel/setup.bash

If you have multiple catkin workspaces for multiple versions of ROS, you must source the setup file from inside the workspace you want to use.

Bring ROSARIA into the workspace

Next you will need to download the rosaria source code from its repository.

rosws set amor-ros-pkg https://code.google.com/p/amor-ros-pkg/ --hg -v fuerte
rosws update amor-ros-pkg

cd ~/catkin_ws/src
git clone https://github.com/amor-ros-pkg/rosaria.git

Install ARIA and Build ROSARIA

Do not forget to do ...
$ source ~/ros-fuerte/setup.bash
... in every open terminal.

RosAria uses the Aria library from Adept MobileRobots to communicate with the robot.

  sudo dpkg -i libaria_2.9.1+ubuntu12_i386.deb

  sudo dpkg -i libaria_2.9.1+ubuntu16_i368.deb

  cd /usr/local/Aria
  make clean
  make -j4

Alternative AriaCoda version

If the robots.mobilerobots.com website or the ARIA download are no longer available, then a modified fork of ARIA is also available by cloning or forking http://github.com/reedhedges/AriaCoda. Build from source code and install. See README and other notes about changes from ARIA 2.9.

dpkg-query -W python-rosdep

sudo apt-get update
sudo apt-get upgrade

rosdep update
rosdep install rosaria

Note about Catkin/CMake detection and caching of ARIA library location

Note: rosaria's CMake build script detects the location of the ARIA library when catkin runs cmake. If you have already tried building rosaria prior to installing the ARIA library (either via rosdep or manually), you must force catkin to re-run cmake for rosaria with catkin_make --force-cmake. Do this if you get errors while building rosaria such as "could not find such file or directory : Aria/Aria.h" or siimlar.

Build rosaria

Now build rosaria using catkin. Run this from your catkin workspace directory:

catkin_make 

This will build all packages in the catkin workspace.

You only need to install and build ROSARIA once, or when changing to new versions of ROSARIA or ARIA.

Run roscore

Next, we can start the RosAria node. First, run roscore from your ros workspace, if you have not done so already:

roscore

roscore must always be running for any other ROS node in this ROS node network to work and communicate. It only needs to run once, however, you don't need to run it every time you restart RosAria.

If you are running different nodes on different computers, only one roscore is needed, but its hostname (address) must be specified when running nodes on other computers. The RosAria node must run on a computer connected to the robot controller -- either the robot's (primary) onboard computer, or a laptop connected via serial connector to the robot HOST serial port.

Run the RosAria node

Next, run the !RosAria node from the rosaria package.

If necessary, open a new terminal window. If you have not yet done so in this terminal windows or shell, and you have not set up your .bashrc file to do so automatically, source the catkin setup script in your workspace:

cd catkin_ws
. devel/setup.bash

Unless the computer running RosAria has a DNS entry that client programs and other nodes can use to locate it, you must also set the ROS_IP environment variable before running RosAria. Normally ROS provides the local computer's hostname to other nodes, but if they cannot use this hostname, then they will not be able to connect to the RosAria node. The ROS_IP environment variable explicitly specifies the IP address to use. For example, if your computer has IP address 10.0.126.32 set ROS_IP as follows before running RosAria:

export ROS_IP=10.0.126.32

Substitute the correct IP address if different. If you are using a wireless network, use the IP address for the wireless ethernet interface (usually wlan0, wifi0, or ath0).

Next, run the RosAria node:

rosrun rosaria RosAria

rosrun ROSARIA RosAria

The first argument to rosrun specifies the package name, "rosaria". The second argument to rosrun specifies the node name, "RosAria".

Additional parameters may be set via rosrun. See below for details.

If you receive an error regarding connecting to the robot on port /dev/ttyUSB0 or similar, you may need to specify a different port via the ~port parameter. See the section below on "RosAria Parameters" for more information.

To disconnect, then reconnect with the robot, kill RosAria (by pressing Ctrl-C or using the kill command) and re-run it.

Only one program can connect to the robot at a time, so only one instance of the rosaria node (or any other program connected to the robot, such as one of the demo/example/server programs provided with ARIA or ARNL, or the p2os node) can run at a time.

Note, if you ran roscore on a different computer, set the ROS_MASTER_URI environment variable first to reference that roscore server. For example, if you ran roscore on a computer with address 10.0.100.1, set it like this:

export ROS_MASTER_URI=http://10.0.100.1:11311

You must also set ROS_MASTER_URI before running any other nodes or client programs on computers other than the computer running roscore.

RosAria Parameters

RosAria has a port parameter that specifies which serial port to use to connect to the robot, or it may contain a hostname and TCP port to connect remotely over TCP (for example, to connect to an AmigoBot or other robot that uses a wifi serial-bridge or to to a MobileSim simulator running on a different host.) The port parameter may be given on the command line when running the RosAria node with rosrun, or it may be changed using rosparam (before staring RosAria, or restart RosAria.) The value will be saved in the ROS parameters and reused next time you run RosAria.

The default port is /dev/ttyUSB0, which will work if you have connected your Linux laptop or other computer to the robot via a USB-serial adapter, and also on the Pioneer LX which uses USB-serial adapters:

rosrun rosaria RosAria

To specify the port as /dev/ttyS0 (COM1, normal for most robot onboard computers) instead, use:

rosrun rosaria RosAria _port:=/dev/ttyS0

Make sure you have added your user to the "dialout" group (sudo usermod -a -G dialout $USER), or change the permissions of the serial port device to allow all users to access it (e.g. sudo chmod a+rw /dev/ttyUSB0 or sudo chmod a+rw /dev/ttyS0). You can check the Linux kernel logs by running dmesg after plugging in the USB-serial converter to see the name of the device interface being used.

If you have a robot with a wireless ethernet-serial bridge device with IP address 10.0.126.32, use the following command instead:

rosrun rosaria RosAria _port:=10.0.126.32:8101

If using the onboard computer on a Pioneer 3, Pioneer 2, PeopleBot, PowerBot or PatrolBot, use /dev/ttyS0 as in the example above. IF you are using the embedded computer in a Pioneer LX, use /dev/ttyUSB0.

Note that only one instance of the RosAria node may run at one time, stop any other RosAria instances before running a new one.

In addition to the port parameter, RosAria also accepts other parameters as well. See ROSARIA for a full list.

Note: When you specify a parameter using rosrun, the ROS parameter system automatically stores this setting for future use, and will use the previously set value if the parameter is omitted. Specify a new value to change.

Example Client Programs

An example set of client programs with a text-based interactive interface for running them is available from https://github.com/pengtang/rosaria_client. Read the README file for instructions. These example programs show how to publish or subscribe to ROSARIA's topics, and can be used to interactively test or demonstrate ROSARIA controlling the robot.

Launch files and other configuration

A set of configuration files including roslaunch files, URDF, etc is available from http://github.com/MobileRobots/amr-ros-config

Using MobileSim simulator

MobileSim is a simulator for use with ARIA. It provides a simple 2D simulation scalable to many robots, and useful for software testing. (It is actually based on Stage version 2.)

ARIA automatically detects MobileSim if it is running on the same computer, and will connect to it. Or, you can explicitly set it using RosAria's ~port parameter:

rosrun rosaria RosAria _port:=localhost:8101

MobileSim will emulate the robot base (i.e. velocity commands from the cmd_vel topic and a position estimate given via pose or odom topics -- see below) and sonar (sonar topic -- see below), but connection to other devices such as laser, camera, etc. are through separate nodes in ROS and cannot currently be connected to MobileSim.

For more full-featured simulation in ROS, use stdr_simulator, Stage or Gazebo instead.

Topics and Commands

RosAria provides several topics for publishing information received from the robot and devices by ARIA, and for receiving commands. These follow ROS conventions and use standard ROS datatypes and units. For example, it uses a "twist" for velocity commands, even though only some components apply to differential drive ground mobile robots, and units are translated to meters and radians as used in ROS from the millimeters and degrees used by the robot and ARIA.

Pose

RosAria publishes the current pose estimation received from the robot in /RosAria/pose. The type of this data is nav_msgs/Odometry. (This pose estimation is calculated by the robot firmware as ARIA based on wheel odometry, and if preset, the optional internal gyroscope.)

This pose estimation is received from the robot every 100ms (by default), and is then published on the /RosAria/pose topic.

To view /RosAria/pose using rostopic use:

rostopic echo /RosAria/pose

Press Ctrl-C to stop.

Velocity Commands

The desired velocity of the robot is set via the /RosAria/cmd_vel topic. This desired velocity state is set in ARIA, which sends commands every robot cycle (100ms by default) to effect this state in the robot's embedded motion controller, which performs motor control to achieve then maintain the robot velocity automatically (using previously configured acceleration parameters).

You do not need to send commands at any fixed rate to maintain robot velocity, ARIA and the robot controller maintain the velocities. Velocity commands only need to be sent to change the desired velocities.

A standard type for robot motion commands in ROS is geometry_msgs/Twist, which contains many components (dimensions). The relevant twist components for Pioneer mobile robots are linear x (forward/back translational velocity) and angular z (rotational velocity). (In future, the Seekur robot will accept linear y for lateral velocity as well.)

The syntax for specifying twist data using the rostopic command is as follows (this example sets a linear velocity of 0.1 meters/s):

rostopic pub -1 /RosAria/cmd_vel geometry_msgs/Twist '[0.1, 0.0, 0.0]' '[0.0, 0.0, 0.0]'

Sonar

RosAria also provides the /RosAria/sonar topic for sonar readings. The type of this topic is a 2-dimensional sensor_msgs/PointCloud.

Bumpers

RosAria also provides /RosAria/bumper_state for bumper switch state:

BumperState contains two boolean arrays, front_bumpers and rear_bumpers)

Battery State

RosAria publishes a /RosAria/battery_state_of_charge topic for robot models which provide battery state-of-charge data (Pioneer LX, Seekur, Seekur Jr.). This is a charge percentage from 0.0 to 1.0. If a robot does not provide state-of-charge data, then this topic is not published.

RosAria publishes /RosAria/battery_voltage topic for all robot models. This is a battery voltage measurement (volts DC).

Recharging Status

RosAria can provide status on recharging a Pioneer LX robot, via the /RosAria/battery_recharge_state topic.

This is an 8-bit integer which is 0 if not charging, > 0 if recharging, and < 0 on error or no data. (Specifically -2 means no data; -1 unknown state; 0 not recharging; 1 bolk recharge; 2 overcharge state; 3 float)

If a robot does not provide recharge status, then this topic is not published.

Enable/Disable Motors

Whether the robot's motors are enabled or disabled is published as a boolean value via the /RosAria/motors_state topic.

To enable the motors, use the /RosAria/enable_motors service. To disable the motors, use the /RosAria/disable_motors service.

RosAria enables the motors when it connects to the robot, but some robots require motors to be explicitly re-enabled after the e-stop button is pressed (e.g. Pioneer LX) or a bumper hit occurs (e.g. Seekur).

Laser Rangefinders

You can optionally configure RosAria to connect to any laser rangefinder sensors configured in the ARIA robot parameters, and provide that data as well as robot data. Set the ~publish_aria_lasers parameter to true on the command line with rosrun or in your roslaunch file. For example: rosrun rosaria RosAria _publish_aria_lasers:=true.

Or, you may run a ROS node specific to your laser type. These nodes will be configurable through ROS parameters and may provide more ROS-specific data. See Robots/Pioneer for more discussion of lasers, including notes specific to the LMS-200 and Pioneer 3 robot, and for links to documentation on various ROS nodes supporting various laser rangefinder types.

Note that you will need to disable ~publish_aria_lasers if you have previously run RosAria with ~publish_aria_lasers set to true. For example: rosrun rosaria RosAria _publish_aria_lasers:=false.

Other Topics

Other topics may be added in the future as well.

See ROSARIA for the current, complete list.

Acceleration Parameters

Acceleration and deceleration parameters may be adjusted via dynamic_reconfigure: trans_accel, trans_decel, rot_accel, rot_decel, lat_accel, lat_decel. These are sent to the robot controller and it will use them as soon as any requested velocity changes to achieve that change in velocity.

Odometry Calibration

It is possible to modify odometry/position integration parameters (TicksMM, DriftFactor, RevCount) via dynamic_reconfigure. These parameters will be stored and re-set whenever the RosAria node runs.

If these parameters are not set, then the robot controller will use its saved values, usually these are default values for that model robot, but can be changed using the robot controller firmware configuration tool. Defaults often work fine for most robots, but you can tweak the calibration if you want to try to improve it slightly to adjust for worn tires or other differences in your individual robot.

If these calibration parameters are set and RosAria is changing them at startup, then RosAria will print a log message indicating that it is using these parameters and sending them to the robot.

Useful utilities and companion nodes

For a list of nodes used with some common accessory devices used on Pioneer robots, see Robots/AMR_Pioneer_Compatible#Hardware_Drivers_and_Simulation.